home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-19 / intrlib1.zip / INTR_LIB.DOC < prev    next >
Text File  |  1992-02-26  |  34KB  |  781 lines
  1.                 INTR_LIB 1.0
  2.                 ------------
  3.  
  4.  
  5.   BECAUSE INTR_LIB AND ITS SUPPORTING TOOLS AS DOCUMENTED IN THIS DOCUMENT
  6. ARE LICENSED FREE OF CHARGE, I PROVIDE ABSOLUTELY NO WARRANTY, TO THE EXTENT
  7. PERMITTED BY APPLICABLE STATE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING, I
  8. GERSHON ELBER PROVIDE INTR_LIB PROGRAM AND ITS SUPPORTING TOOLS "AS IS"
  9. WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
  10. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  11. PARTICULAR PURPOSE.
  12. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THESE PROGRAMS IS WITH
  13. YOU. SHOULD THE INTR_LIB PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
  14. NECESSARY SERVICING, REPAIR OR CORRECTION.
  15.  
  16.   IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL GERSHON ELBER,
  17. BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES,
  18. OR OTHER SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
  19. USE OR INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR A
  20. FAILURE OF THE PROGRAMS TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY GERSHON
  21. ELBER) THE PROGRAMS, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF
  22. SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY.
  23.  
  24. This file provide some information about the INTR_LIB tool - an interaction
  25. graphics library for MSDOS environment. This library provide basic windowing
  26. facilities, pop up and pull down menus, and support keyboard, mouse and
  27. joystick devices.
  28.     This library can currently be compiled for MSDOS using Borland's BC++
  29. compiler or DJGPP - the gcc port for 386 machines. Porting for other
  30. environment is feasible by rewriting one file - see intr_bgi.c and intr_djg.c
  31. for example.
  32.  
  33.     Applications wishes to use the library should include intr_lib.h which
  34. is the main interface. Under some conditions intr_gr.h may be needed as well.
  35. This may be true mainly for low level drawing routines (lines, arcs, etc.).
  36.  
  37.     Most functionality of this library is based on selection and abortion
  38. operations. The SELECT is specified by the left mouse button, the space
  39. bar, or button one of the joystick. The ABORT is specified by the right mouse
  40. button, the Enter key, or button two of the joystick. Several other events
  41. may occur and include middle mouse button event (two button mouse can
  42. generate it by pressing both buttons simultanuously), cursor movement
  43. keystroke or window refresh request. See IntrEventType in intr_lib.h
  44.  
  45.     Screen pixel coordinates are rarely used in this library. The mouse
  46. location is specified in this coordinate system but mapping routines are
  47. provided to map it to window coordinates.
  48.     Drawing into windows is always done in window (not screen) coordinates.
  49. Two equivalent coordinate systems are provided for each window. The first
  50. uses the window pixel coordinate system where (0, 0) is the window (not
  51. screen) corner, and (x, y) are specified in pixels for zero to window
  52. pixel width and height. The second coordinate system provided for each
  53. window is normalized. The user specifies the bounding box of the normalized
  54. coordinate system, say from (-1.0, -1.0) to (1.0, 1.0) (see IntrWndwSetFBBox)
  55. and these locations will be mapped to the entire screen. For the above
  56. example (-1.0, -1.0) will match one corner of the window, (1.0, 1.0) the
  57. other corner (diagonally) and (0.0, 0.0) will always be the window center.
  58. Note that windows can have any aspect ratio, so aspect ratio correction
  59. should be imbedded into this FBBox.
  60.  
  61.     During a session this package is used, there may be a Selected Window
  62. and a Drawing Window. A Selected window is a window with highlighted colors.
  63. Default is to have no selected window. Drawing window is the window all
  64. drawing command are going to. There are several routines to control both.
  65.  
  66.     To isolate as much as possible the data structures from the application
  67. windows are specified using an integer id, referred as WindowID in most
  68. functions below.
  69.  
  70.     Colors are specified in two levels, in this library. All the windowing
  71. widget uses a four intensity level scheme (if enough colors are provided)
  72. via IntrColorType and IntrIntensityType. Each color in IntrColorType has
  73. four intensity levels 9See intr_lib.h). This is the way the window borders
  74. are created, for example.
  75.     The regular (line, circle, etc.) drawing routines specified direct
  76. color via the colors in the supporting package (BGI graphics.h interface for
  77. BC++ with intr_gr.h, or DJGPP graphics.h with intr_gr.h). The colors are
  78. specified via the GRSetColor command (see intr_gr.h).
  79.  
  80.     This file barely document the intr_lib portion of this package. intr_gr.h
  81. which is the low level drawing interface is not documented. Most routines
  82. there follows Borland's BGI interface and so one may refer to their...
  83.  
  84.     I am not even close to being happy with this documentation. Given my
  85. time constraints i have, this is the maximum I can do. if you feel like
  86. writing a better one, I will be very happy to hear from you. If you find
  87. bugs and fixed them, I will be happy to hear that too. If you find a bug
  88. and cannot fix it, drop me a message, but I provide no guarantee.
  89.  
  90. Gershon Elber
  91.  
  92. gershon@gr.utah.edu
  93.  
  94. -----------------------------------------------------------------------------
  95.  
  96. General library control
  97. -----------------------
  98. void IntrInit(void);
  99.     Initialize the library. Should be invoked before any other function
  100.     in this library. This routine will also switch to graphics mode.
  101.  
  102. void IntrClose(void);
  103.     Close the library. No other function from this library should be
  104.     called after this routine. This routine switch back to text mode.
  105.  
  106. void IntrFatalError(char *Msg);
  107.     Mainly internal routine to close the library and print a fatal error
  108.     message.
  109.  
  110. int IntrPopUpActive(void);
  111.     Returns 0 iff no window is currently poped up. Otherwise returns
  112.     number of poped up windows.
  113.  
  114. Color allocation routines
  115. -------------------------
  116. int IntrAllocColor(IntrColorType Color, IntrIntensityType Intensity);
  117.     Mainly internal routine to allocate a color with specific intensity.
  118.     Returns the color index.
  119.  
  120. void IntrAllow256Colors(IntrBType Allow256Colors);
  121.     On devices that support 256 colors, the default behaviour is to
  122.     support and use only 16 colors (to be compatible with EGA/VGA 16
  123.     colors mode). If invoked with TRUE, then all 256 colors may be used
  124.     for more fine colors. This function has no affect under DJGPP which
  125.     always use 256 colors.
  126.  
  127. Window manipulation routines
  128. ----------------------------
  129. int IntrWndwCreate(char *WindowName,
  130.            int FrameWidth,
  131.            IntrBBoxStruct *BBox,
  132.            IntrColorType FrameColor,
  133.            IntrColorType BackColor,
  134.            IntrCursorShapeStruct *Cursor,
  135.            IntrPullDownMenuStruct *PDMenu,
  136.            IntrIntFunc RefreshFunc);
  137.     Create an instance of a window. This routine DOES NOT make the window
  138.     visible (See IntrWndwPop below). Specified are the window name,
  139.     its size bbox (of the drawable portion, not including the frame),
  140.     width of the window frame in pixels and its color, the window back
  141.     ground color, type of cursor to use under this window, optional
  142.     pull down menu for this window, and an optional refresh function.
  143.       The pull down menu may be created by IntrPullDownMenuCreate. NULL
  144.     means no pull down menu for this window.
  145.       The refresh function is a function that should redraw the window
  146.     should it be resized, poped up, etc. This routine should assume
  147.     that viewport is set at time of invocation and that the window is
  148.     all visible. The function gets one parameter which is the window id
  149.     (in case the same function is used to update several windows).
  150.       Most of these parameters may be get/set via specific functions
  151.     (see below).
  152.  
  153. void IntrWndwSetRoot(int RootWindowID);
  154.     Sets a window to be a root window. A root window cannot be poped up
  155.     and will always be below all other windows.
  156.  
  157. void IntrWndwSelect(int WindowID);
  158.     Make this window the selected window. The selected window frame
  159.     will drawn intensified. Generally there is only one selected window
  160.     unless all windows are selected (default behaviour). See also
  161.     IntrWndwSelectAll.
  162.  
  163. void IntrWndwSelectAll(IntrBType SelectAll);
  164.     If TRUE all windows are considered selected (default). If FALSE only
  165.     the one as set by IntrWndwSelect is selected.
  166.  
  167. void IntrWndwRedrawAll(void);
  168.     Redraw all windows. This routine will also invoke the refresh function
  169.     foreach window, if it has one.
  170.  
  171. void IntrWndwClear(int WindowID);
  172.     Clear the specified window to its background color. This routine
  173.     also make this window the drawing window.
  174.  
  175. int IntrWndwPick(void);
  176.     Picks a window by asking the user to click SELECT while the cursor
  177.     is on the to be picked window. Returned is the picked window id,
  178.     -1 if no window was picked (clicked on background), 0 if ABORT.
  179.  
  180. void IntrWndwPop(int WindowID, IntrBType DoRedraw, IntrBType DoClear);
  181.     Pops up the specified window. If DoRedraw then the redraw function
  182.     of this window (if it has one) is invoked. If DoClear then window
  183.     is only cleared. If the window was unvisible (a newly created or
  184.     hidden by IntrWndwHide) then it will become visible.
  185.  
  186. void IntrWndwPush(int WindowID, IntrBType DoRedraw);
  187.     Pushes down the specified window. If DoRedraw then the redraw function
  188.     of this window (if it has one) is invoked. If the window was unvisible
  189.     (a newly created or hidden by IntrWndwHide) then it will become visible.
  190.     
  191. IntrBType IntrWndwIsAllVisible(int WindowID);
  192.     A Boolean predicate that returns TRUE iff the entire window is
  193.     visible, i.e. not hidden by any other window.
  194.  
  195. void IntrWndwSetResizeBBox(IntrBBoxStruct *BBox);
  196.     Controls the maximum domain IntrWndwResize will allow a window to
  197.     be resized. This allows for example to control resizing of a window
  198.     in a certain region in the screen.
  199.  
  200. IntrBType IntrWndwMove(int WindowID, IntrBType Refresh);
  201.     Moves the specified window. If Refresh then the screen will be
  202.     refreshed to reflect the new location.
  203.  
  204. IntrBType IntrWndwResize(int WindowID, IntrBType Refresh);
  205.     Resize the specified window. If Refresh then the screen will be
  206.     refreshed to reflect the new location. See also IntrWndwSetResizeBBox
  207.     and IntrWndwFullSize.    
  208.  
  209. void IntrWndwFullSize(int WindowID, IntrBType Refresh);
  210.     Resize the specified window to the maximum size allowed as specified
  211.     by IntrWndwSetResizeBBox. If Refresh then the screen will be refreshed
  212.     to reflect the new location.
  213.     
  214. void IntrWndwHide(int WindowID, IntrBType Refresh);
  215.     Make a window invisible. The window is not modified in any other way
  216.     and can be made visible any time after using IntrWndwPush/Pop.
  217.     If Refresh is TRUE then the screen is actually refreshed to reflect
  218.     on the hidden window.
  219.  
  220. void IntrWndwDelete(int WindowID, IntrBType Refresh);
  221.     Same as IntrWndwHide but this window is deleted and should be be
  222.     referenced any more.
  223.  
  224. int IntrWndwGetHeaderHeight(char *Header, int FrameWidth);
  225.     Mainly internal routine to compute the height of the window header
  226.     given the header string and the frame width.
  227.  
  228. IntrBBoxStruct *IntrWndwGetBBox(int WindowID);
  229.     Returns pointer to the specified window bbox size.
  230.  
  231. IntrFBBoxStruct *IntrWndwGetFBBox(int WindowID);
  232.     Returns pointer to the specified window bbox of normalized coordinates.
  233.  
  234. IntrColorType IntrWndwGetFrameColor(int WindowID);
  235.     Returns the specified window frame color.
  236.  
  237. IntrColorType IntrWndwGetBackGroundColor(int WindowID);
  238.     Returns the specified window background color.
  239.  
  240. IntrCursorShapeStruct *IntrWndwGetCursorShape(int WindowID);
  241.     Returns pointer to the specified window cursor shape.
  242.  
  243. IntrPullDownMenuStruct *IntrWndwGetPullDownMenu(int WindowID);
  244.     Returns pointer to the specified window pull down menu.
  245.  
  246. int IntrWndwGetZoomFactor(int WindowID);
  247.     Returns the specified window zoom factor.
  248.  
  249. IntrIntFunc IntrWndwGetRefreshFunc(int WindowID);
  250.     Returns pointer to the specified window refresh function.
  251.  
  252. void IntrWndwGetPanFactors(int WindowID, int *x, int *y);
  253.     Returns the specified window pan factor.
  254.  
  255. void IntrWndwSetName(int WindowID, char *Name);
  256.     Sets the specified window name.
  257.  
  258. void IntrWndwSetDrawHeader(int WindowID, IntrBType DrawHeader);
  259.     Sets the specified window draw header boolean flag. If TRUE window
  260.     header is drawn, if FALSE it is not.
  261.  
  262. void IntrWndwSetBBox(int WindowID, IntrBBoxStruct *BBox);
  263.     Sets the specified window BBox. This has the affect of resizing the
  264.     window although the screen has to be refreshed for this to be
  265.     visible (see IntrWndwRedrawAll).
  266.  
  267. void IntrWndwSetFBBox(int WindowID, IntrFBBoxStruct *FBBox);
  268.     Sets the specified window normalized coordinates.
  269.  
  270. void IntrWndwSetFrameColor(int WindowID, IntrColorType FrameColor);
  271.     Sets the specified window frame color.
  272.  
  273. void IntrWndwSetBackGroundColor(int WindowID, IntrColorType BackColor);
  274.     Sets the specified window back ground color.
  275.  
  276. IntrBType IntrWndwIsScrollBarEvent(int WindowID,
  277.                    IntrBType *IsVertical,
  278.                    IntrRType *Value);
  279.     Mainly internal routine to handle scroll bar event.
  280.  
  281. int IntrWndwScrollBarWidth(void);
  282.     Returns the width in pixels of the scroll bar.
  283.  
  284. void IntrWndwUpdateScrollBar(int WindowID,
  285.                  IntrBType IsVertical,
  286.                      IntrRType RelativePosition,
  287.                              IntrRType DisplayedFraction);
  288.     Updates a vertical (IsVertical is TRUE) or an horizontal (FALSE)
  289.     scroll bar of the specified window by specifing the active window
  290.     visible fraction and relative position.
  291.     
  292. void IntrWndwSetScrlBar(int WindowID,
  293.             IntrBType IsVertical,
  294.             IntrScrlBarType ScrlBar,
  295.                         IntrColorType ScrlBarColor);
  296.     Enable a vertical (IsVertical is TRUE) or an horizontal (FALSE)
  297.     scroll bar for the specified window. be default a window does
  298.     not have a scroll bar.
  299.  
  300. void IntrWndwSetCursorShape(int WindowID, IntrCursorShapeStruct *Cursor);
  301.     Sets the specified window Cursor shape.
  302.  
  303. void IntrWndwSetPullDownMenu(int WindowID, IntrPullDownMenuStruct *PDMenu);
  304.     Sets the specified window pull down menus.
  305.  
  306. void IntrWndwSetRefreshFunc(int WindowID, IntrIntFunc RefreshFunc);
  307.     Sets the specified window refresh function.
  308.  
  309. void IntrWndwUpdatePanning(int WindowID, int x, int y);
  310.     Relatively increment the panning of the specified window.
  311.  
  312. void IntrWndwSetPanning(int WindowID, int x, int y);
  313.     Sets the specified window panning factors.
  314.  
  315. void IntrWndwUpdateZoom(int WindowID, int Zoom);
  316.     Relatively increment the zoom factor of the specified window.
  317.  
  318. void IntrWndwSetZoom(int WindowID, int Zoom);
  319.     Sets the specified window zoom factors.
  320.  
  321. void IntrWndwSetStatus(int WindowID, char *StatusLeft, char *StatusRight,
  322.                                 IntrBType Refresh);
  323.     Updates the window header left and right status strings. A window
  324.     can display two strings at the left and right side of its header
  325.     (if the header is displayed obviously). If Refresh the screen is
  326.     refreshed to reflect this change.
  327.  
  328.  
  329. Window drawing routines
  330. -----------------------
  331. void IntrWndwILine(int x1, int y1, int x2, int y2);
  332.     Draw a line in the drawing window using window pixel coordinates.
  333.  
  334. void IntrWndwRLine(IntrRType x1, IntrRType y1, IntrRType x2, IntrRType y2);
  335.     Draw a line in the drawing window using window normalized coordinates.
  336.  
  337. void IntrWndwIMoveTo(int x, int y);
  338.     Move to a new location in the drawing window using window pixel
  339.     coordinates.
  340.  
  341. void IntrWndwRMoveTo(IntrRType x, IntrRType y);
  342.     Move to a new location in the drawing window using window normalized
  343.     coordinates.
  344.  
  345. void IntrWndwILineTo(int x, int y);
  346.     Line to a new location in the drawing window using window pixel
  347.     coordinates.
  348.  
  349. void IntrWndwRLineTo(IntrRType x, IntrRType y);
  350.     Line to a new location in the drawing window using window normalized
  351.     coordinates.
  352.  
  353. void IntrWndwIMoveRel(int x, int y);
  354.     Move to a new location relative to current location in the drawing
  355.     window using window pixel coordinates.
  356.  
  357. void IntrWndwRMoveRel(IntrRType x, IntrRType y);
  358.     Move to a new location relative to current one in the drawing window
  359.     using window normalized    coordinates.
  360.  
  361. void IntrWndwILineRel(int x, int y);
  362.     Line to a new location relative to current one in the drawing window
  363.     using window pixel coordinates.
  364.  
  365. void IntrWndwRLineRel(IntrRType x, IntrRType y);
  366.     Line to a new location relative to current one in the drawing window
  367.     using window normalized    coordinates.
  368.  
  369. void IntrWndwIPoly(int n, int *Points, int Fill);
  370.     Draw a polyline in the drawing window using window pixel coordinates.
  371.     The polyline is specified by its length n and a vector of 2n integers
  372.     as x1, y1, x2, y2, ... xn, yn - Points. If Fill is TRUE the polyline
  373.     is assumed to be simple closed polygons which is filled.
  374.  
  375. void IntrWndwIBar(int x1, int y1, int x2, int y2);
  376.     Draw a filled rectangle in the drawing window using window pixel
  377.     coordinates.
  378.  
  379. void IntrWndwRBar(IntrRType x1,
  380.           IntrRType y1,
  381.           IntrRType x2,
  382.           IntrRType y2);
  383.     Draw a filled rectangle in the drawing window using window normalized
  384.     coordinates.
  385.  
  386. void IntrWndwICircle(int x, int y, int r);
  387.     Draw a circle in the drawing window using window pixel coordinates.
  388.     Circle center is at (x, y) and radius r.
  389.  
  390. void IntrWndwRCircle(IntrRType x, IntrRType y, IntrRType r);
  391.     Draw a circle in the drawing window using window normalized coordinates.
  392.     Circle center is at (x, y) and radius r.
  393.  
  394. void IntrWndwIArc(int x, int y, int StAngle, int EndAngle, int r);
  395.     Draw an arc in the drawing window using window pixel coordinates.
  396.     The arc center is at (x, y) with starting and ending angles and of
  397.     radius r.
  398.  
  399. void IntrWndwRArc(IntrRType x,
  400.           IntrRType y,
  401.           int StAngle,
  402.           int EndAngle,
  403.           IntrRType r);
  404.     Draw an arc in the drawing window using window normalized coordinates.
  405.     The arc center is at (x, y) with starting and ending angles and of
  406.     radius r.
  407.  
  408. void IntrWndwIText(int x, int y, char *s);
  409.     Draw the specified text string in the drawing window at the specified
  410.     location in pixel coordinates. See also GRSetTextJustify.
  411.  
  412. void IntrWndwRText(IntrRType x, IntrRType y, char *s);
  413.     Draw the specified text string in the drawing window at the specified
  414.     location in normalized coordinates. See also GRSetTextJustify.
  415.  
  416. Text handling in graphic windows
  417. --------------------------------
  418. void IntrTextInitWindow(int WindowID,
  419.             IntrBType ReadBottomLine,
  420.             IntrColorType TextColor,
  421.                         IntrColorType BottomLineColor,
  422.                         IntrScrlBarType HScrlBar,
  423.                         IntrScrlBarType VScrlBar,
  424.                         int NumOfLines,
  425.                         int LineLen);
  426.     Initialize a window to handle text. This routine makr the window
  427.     as text window and initialize the necessary data structure for such
  428.     support. If ReadBottomLine is TRUE then it is assumed this window
  429.     will be used to read text interactively via IntrGetLineWindow.
  430.     Text colors are specified as well as possible scroll bars for the
  431.     window. Number of lines to save (which can be viewed by clicking
  432.     on the scroll bar and therefore can be more than can be displayed
  433.     at once) and there maximal length is also specified.
  434.  
  435. void IntrTextSetSmoothScroll(IntrBType SmoothScrolling);
  436.     By default text is scrolled by clearning the entire screen and
  437.     drawing the new text. If SmoothScrolling is TRUE smooth scrolling
  438.     (but slower one) will take affect.
  439.  
  440. void IntrTextWndwRefresh(int WindowID);
  441.     A refresh function for a text window. May be used in IntrWndwCreate.
  442.  
  443. void IntrPrintf(int WindowID, IntrBType UpdateWindow, char *CtrlStr, ...);
  444.     A printf equivalent routine to printf directly to a text window.
  445.  
  446. void IntrGetLineWindow(int WindowID, char *Buffer, int BufferLen);
  447.     A routine to get a single line into Buffer with maximal length
  448.     BufferLen in the specified window bottom line. Full line editing
  449.     is provided via left/right arrow keys, backspace, home/end and esc
  450.     to clear the line. The up/down arrow keys provide history buffer of
  451.     10 last line entries.
  452.  
  453. Cursor control routines
  454. -----------------------
  455. void IntrUseMouseDriverCursor(IntrBType UseMouseCursor);
  456.     If TRUE attempt is made to use the mouse driver internal mouse support.
  457.     By default only intr_lib cursors are used.
  458.  
  459. void IntrPushCursorType(void);
  460.     A simple stack mechanism to preserve the current cursor type.
  461.     Can be restored via IntrPopCursorType.
  462.  
  463. void IntrPopCursorType(void);
  464.     Restore the last pushed cursor -see IntrPushCursorType.
  465.  
  466. IntrCursorShapeStruct *IntrGetCursorType(void);
  467.     Returns current cursor type.
  468.  
  469. void IntrSetCursorType(IntrCursorShapeStruct *Cursor);
  470.     Set a new cursor type. See IntrCursorType for different cursor types.
  471.  
  472. void IntrSetCursorType2(IntrCursorType CursorType,
  473.                 void (* CursorRoutine)(int, int),
  474.                 int Width, int Height, int LastX, int LastY,
  475.                 IntrBType LastHV);
  476.     Mainly internal routine to draw cursor shapes.
  477.  
  478. void IntrShowCursor(int x, int y);
  479.     Display the currently selected cursor at the screen pixel specified
  480.     coordinate.
  481.  
  482. void IntrReposCursor(int x, int y);
  483.     Move and redraw a cursor at a new location.
  484.  
  485. void IntrUnShowCursor(void);
  486.     Display the currently selected cursor at the screen pixel specified
  487.     coordinate.
  488.  
  489. Simple messages mechanism
  490. -------------------------
  491. void IntrDrawMessage(char *Str, IntrColorType ForeColor,
  492.                             IntrColorType BackColor);
  493.     A simple widget to temporary display a message with the specified
  494.     colors. Message is displayed at the screen top left corder.
  495.     Message can be erase on IntrEraseMessage below.
  496.  
  497. void IntrEraseMessage(void);
  498.     See IntrDrawmessage above.
  499.  
  500. Input event handling routines
  501. -----------------------------
  502. int IntrGetch(void);
  503.     get one character from keyboard or wait for one if none was pressed
  504.     yet. If an extended key was pressed (such as a PF key) it will
  505.     be returned as 0 followed by the extended code in the next call.
  506.  
  507. int IntrKbHit(void);
  508.     Returns non zero if keyboard buffer is not zero. Never wait for
  509.     input.
  510.  
  511. void IntrSetIdleFunction(IntrVoidFunc IdleFunction);
  512.     When waiting for events, this routine may be invoke to do something
  513.     useful. This routine should complete its task in a fraction of a
  514.     second to provide a reasonable response time in event handling.
  515.  
  516. void IntrSetAtKeyboard(IntrBType IsATKeyboard);
  517.     If the systme is an AT type (TRUE), a more advanced keyboard is
  518.     assumed which support more codes such as F11 and F12. On DJGPP
  519.     this routine is ignored.
  520.  
  521. void IntrSetMouseSensitivity(int Sensitivity);
  522.     Provide control on mouse seinsitivity...
  523.  
  524. IntrBType IntrRegisterKeyStroke(int KeyStroke, IntrIntFunc ActionFunc);
  525.     Provide an async. method to invoke a function when the specified
  526.     keystroke is detected. KeyStroke is a regular ascii code for regular
  527.     keystrokes or +256 if extended code. ActionFunction can for example
  528.     be a function to pop up a menu. Up to 50 keystrokes can be registered
  529.     Not way is currently provided to unregister a key.
  530.  
  531. void IntrSetInputDevice(int Devices);
  532.     Sets which input devices should be handled. Currently the keyboard,
  533.     mouse, and joystick are the supported devices. See IntrInputDeviceType
  534.     in intr_lib.h. The different device types are ORed together to
  535.     define the set of input devices to support.
  536.  
  537. void IntrSetHandleInternalEvents(IntrBType HandleEvents,
  538.                  IntrBType PropagateEvents);
  539.     Control automatic handling of internal events (such as SELECT event
  540.     on a scroll bar which generally means update the window with scroll
  541.     bar in new specifid location). If HandleEvents (TRUE by default)
  542.     then this will be done automatically. If PropagateEvents (TRUE by
  543.     default) then the events will also be propagated to the application
  544.     program. Make PropagateEvents FALSE will total hide this automatic
  545.     process from an application program.
  546.  
  547. void IntrInputFlush(void);
  548.     Make sure all input devices queues are empty.
  549.  
  550. IntrEventType IntrGetEventWaitSA(int *x, int *y);
  551.     Wait until either SELECT, ABORT, or MIDDLE_BUTTON event is
  552.     generated. x and y should, in general, be ignored.
  553.  
  554. IntrEventType IntrGetEventWait(int *x, int *y);
  555.     Wait until any event is generated. x and y will hold the current
  556.     cursor position in screen pixel coordinates.
  557.  
  558. IntrEventType IntrGetEventNoWait(int *x, int *y);
  559.     Same as IntrGetEventWait but will return INTR_EVNT_NONE if no event
  560.     is pending on one of the input devices.
  561.  
  562. IntrEventType IntrGetTextEventWait(void);
  563.     Same as IntrGetEventWait but no cursor is displayed.
  564.  
  565. IntrEventType IntrGetTextEventNoWait(void);
  566.     Same as IntrGetEventNoWait but no cursor is displayed.
  567.  
  568. void IntrPushKbdEvent(int KbdEvent);
  569.     One level queue to insert keyboard events to IntrGetEvent{No}Wait
  570.     routines.
  571.  
  572. IntrBType IntrMapEventToWindow(int WindowID, int x, int y, int *Wx, int *Wy);
  573.     Routine to verify if the cursor is on (screen pixel coord (x, y)) the
  574.     specified window (WindowID). If on window, TRUE is returned and Wx, Wy
  575.     are set to this window, window pixel coordinates of the clocation.
  576.     FALSE is return if cursor is not on window.
  577.  
  578. IntrBType IntrMapEventToRWindow(int WindowID, int x, int y,
  579.                           IntrRType *Wx, IntrRType *Wy);
  580.     Same as IntrMapEventToWindow but returned screen coordinates are in
  581.     normalized coordinates instead.
  582.  
  583. Routines to control images back saving
  584. --------------------------------------
  585. void IntrSetAsyncEventMode(IntrBType AsyncMode);
  586.     If AsyncMode is TRUE, All events will be handled all time async.. This
  587.     make be quite confusing when several windows are poped up
  588.     simulanouosly. Up to 20 pop up windows are allowed. Setting it to
  589.     FALSE (default) will allow only one poped up item at the same time.
  590.  
  591. void IntrSetSaveBackGround(IntrBType SaveBackGround);
  592.     Usually, when a window is poped up, the raster display below it is
  593.     automatically being saved (default behaviour). By setting
  594.     SaveBackGround to FALSE this would not occur, but the application
  595.     will have to refresh the screen.
  596.  
  597. void IntrSetSaveBackMethod(IntrSaveMemType SaveBackMethod);
  598.     Allow backsaving (see IntrSetSaveBackGround) to regular memory, ems
  599.     memory, or xms memory (no support yet), or (ram) disk. See
  600.     IntrSaveMemType in intr_lib.h. Note that for the DJGPP version only
  601.     regular linear memory (which you have up to 200M of) is used and this
  602.     function has no affect.
  603.  
  604. void IntrSetSaveBackPath(char *Path);
  605.     If IntrSetSaveBackMethod saves to disk, this routine specifies the
  606.     full path to the saving directory.
  607.  
  608. Query Interaction routines
  609. --------------------------
  610. void IntrQueryContinue(char *Question,
  611.                IntrColorType FrameColor,
  612.                IntrColorType BackColor,
  613.                IntrColorType ForeColor,
  614.                IntrColorType XorColor,
  615.                        int FrameWidth,
  616.                        IntrCursorShapeStruct *Cursor,
  617.                        int WindowID);
  618.     A widget to allow posting a message (Question) to the user. The
  619.     user will have to SELECT the "Continue" button for this function to
  620.     return. If WindowID is a valid window, attempt will be made to
  621.     center the query in that window. Alternatively WindowID can be one
  622.     of INTR_WNDW_PLACE_LEFT/RIGHT/CENTER (see intr_lib.h) in which
  623.     the query will be centered in screen Y but placed accordingly in
  624.     screen X.
  625.  
  626. void IntrQueryContinue2(char *Question,
  627.             void (* ExecFunc)(void),
  628.                 IntrColorType FrameColor,
  629.                 IntrColorType BackColor,
  630.                 IntrColorType ForeColor,
  631.                         int FrameWidth,
  632.                         IntrCursorShapeStruct *Cursor,
  633.                         int WindowID);
  634.     Same as IntrQueryContinue, but invoke ExecFunc to wait for the
  635.     SELECT event. This allows the application to do something useful
  636.     at the meantime.
  637.  
  638. IntrBType IntrQueryYesNo(char *Question,
  639.                  IntrColorType FrameColor,
  640.                  IntrColorType BackColor,
  641.                  IntrColorType ForeColor,
  642.                  IntrColorType XorColor,
  643.                          int FrameWidth,
  644.                          IntrCursorShapeStruct *Cursor,
  645.                          int WindowID);
  646.     Same as IntrQueryContinue but instead of the "Continue" button,
  647.     two "Yes" and "No" button are displayed. TRUE is returned if the "Yes"
  648.     button is SELECTED, FALSE if the "No.
  649.  
  650. char *IntrQueryLine(char *Question,
  651.             char *Buffer,
  652.                     int BufferSize,
  653.             IntrColorType FrameColor,
  654.             IntrColorType BackColor,
  655.             IntrColorType ForeColor,
  656.                     int FrameWidth,
  657.                     int WindowID);
  658.     Same as IntrQueryContinue but instead of the "Continue" button,
  659.     a full line editing capability is provided as follow:
  660.         Left/Right arrows - moves right and left in the line.
  661.         Up/Down arrows - circle a history buffer of last 10 lines.
  662.         Home/End to move to beginning/End of string respectively.
  663.         ESC - totally clears the current edited line.
  664.         Delete - deletes current character.
  665.         Insert - toggle Insert/Overwrite mode.
  666.         Backspace - delete character before current one.
  667.         Return to accept current line and abort editing.
  668.     The line is saved into Buffer which is assumed to be no longer then
  669.     BufferSize. Buffer address is returned by this function.
  670.  
  671. int IntrQueryList(char *Header,
  672.           char **StrEntries,
  673.           int SizeOfEntry,
  674.                   int NumOfEntries,
  675.                   int NumOfDisplayedEntries,
  676.           IntrColorType FrameColor,
  677.           IntrColorType BackColor,
  678.           IntrColorType ForeColor,
  679.           IntrColorType XorColor,
  680.           int FrameWidth,
  681.                   IntrCursorShapeStruct *Cursor,
  682.                   int WindowID);
  683.     Same as IntrQueryContinue but instead of the "Continue" button,
  684.     a whole list (of any length) of items is displayed so one item
  685.     can be picked. List header is specified in Header. The items
  686.     may be specified in two ways:
  687.         * As an array of string pointers StrEntries, each points to a
  688.           string - an item. In this case SizeOfEntry = 0.
  689.         * A linear long string StrEntries (which is in fact of type
  690.           (char *)) where the i'th item is at
  691.         ((char *) StrEntries)[i * SizeOfEntry]
  692.     NumOfEntries specifies how many items exists in the list. If they
  693.     cannot be all displayed simultanouosly, a scroll bar may be used
  694.     to select the ones not currently displayed.
  695.       Returned is the index of the list item picked.
  696.  
  697. Pop Up Menu Interaction routines
  698. --------------------------------
  699. IntrPopUpMenuStruct *IntrPopUpMenuCreate(char *Header,
  700.                      char **StrEntries,
  701.                      int SizeOfEntry,
  702.                                          int NumOfEntries,
  703.                      IntrColorType FrameColor,
  704.                          IntrColorType BackColor,
  705.                          IntrColorType ForeColor,
  706.                          IntrColorType XorColor,
  707.                              int FrameWidth,
  708.                                          IntrCursorShapeStruct *Cursor);
  709.     Constructs a pop up menu. See IntrQueryList for Header, StrEntries,
  710.     SizeOfEntry, and NumOfEntries.
  711.  
  712. void IntrPopUpMenuDelete(IntrPopUpMenuStruct *Menu);
  713.     Delete all memory used by the specified pop up menu. This menu
  714.     should not be referenced any more after this function is called.
  715.  
  716. void IntrPopUpSetEntry(IntrPopUpMenuStruct *PUMenu, char *Entry, int Index);
  717.     Allows a pop up menu entry Index to be changed to Entry. Only menus
  718.     constructed with SizeOfEntry == 0 (see IntrQueryList) can be modified.
  719.  
  720. void IntrPopUpSetHeader(IntrPopUpMenuStruct *PUMenu, char *Header);
  721.     Sets a new header Header for the given pop up menu PUMenu.
  722.  
  723. void IntrPopUpSetFrameWidth(IntrPopUpMenuStruct *PUMenu, int FrameWidth);
  724.     Sets a new frame width for the given pop up menu PUMenu.
  725.  
  726. void IntrPopUpSetColors(IntrPopUpMenuStruct *PUMenu,
  727.                 IntrColorType FrameColor,
  728.                 IntrColorType BackColor,
  729.                 IntrColorType ForeColor,
  730.                 IntrColorType XorColor);
  731.     Sets a new set of colors for the given pop up menu PUMenu.
  732.  
  733. int IntrPopUpMenu(IntrPopUpMenuStruct *PUMenu,
  734.                   int WindowID);
  735.     Actually pops up a menu and make it visible. See IntrQueryContinue
  736.     for WindowID meaning. Returns TRUE if an item was SELECTed from
  737.     menu, FALSE if ABORTed. Note that if an item was selected the selected
  738.     index will be saved in the menu SelectedIndex slot.
  739.  
  740. Pull Down Menu Interaction routines.
  741. ------------------------------------
  742. IntrPullDownMenuStruct *IntrPullDownMenuCreate(char **StrEntries,
  743.                            int SizeOfEntry,
  744.                                                int NumOfEntries,
  745.                            IntrIntFunc *ActionFuncs,
  746.                                IntrColorType FrameColor,
  747.                                IntrColorType BackColor,
  748.                                IntrColorType ForeColor,
  749.                                IntrColorType XorColor,
  750.                                    int FrameWidth);
  751.     Constructs a pull down menu. See IntrQueryList for Header, StrEntries,
  752.     SizeOfEntry, and NumOfEntries. Pull down menus are closely associated
  753.     will regular windows - see IntrWndwCreate. The ActionFuncs array
  754.     specifies which function to invoke when a specified button in the
  755.     menu is activated. Specify NULL to deactivate an entry.
  756.  
  757. void IntrPullDownMenuDelete(IntrPullDownMenuStruct *Menu);
  758.     Delete all memory used by the specified pull down menu. This menu
  759.     should not be referenced any more after this function is called.
  760.  
  761. void IntrPullDownSetEntry(IntrPullDownMenuStruct *PDMenu, char *Entry,
  762.                                 int Index);
  763.     Allows a pull down menu entry string Index to be changed to Entry.
  764.     Only menus constructed with SizeOfEntry == 0 (see IntrQueryList) can
  765.     be modified.
  766.  
  767. void IntrPullDownSetAction(IntrPullDownMenuStruct *PDMenu,
  768.                 IntrIntFunc ActionFunc, int Index);
  769.     Allows a pull down menu entry action function Index to be changed
  770.     to ActionFunc.
  771.  
  772. void IntrPullDownSetFrameWidth(IntrPullDownMenuStruct *PDMenu, int FrameWidth);
  773.     Sets a new frame width for the given pull down menu PUMenu.
  774.     
  775. void IntrPullDownSetColors(IntrPullDownMenuStruct *PDMenu,
  776.                    IntrColorType FrameColor,
  777.                    IntrColorType BackColor,
  778.                    IntrColorType ForeColor,
  779.                    IntrColorType XorColor);
  780.     Sets a new set of colors for the given pull down menu PUMenu.
  781.